Basic Usage#

The Audio function#

The most important function in WaloViz and the reason for it to exist.
When you need the WaloViz player in a jupyter notebook, use the Audio function.

The most simple way to call Audio is like so:

import waloviz as wv

wv.extension()
wv.Audio("https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav")

<class 'bokeh.models.plots.GridPlot'>

Notice that we’ve called the extension function, like the import it should be called once per notebook.

As you can see, the player has all sorts of features, if the default settings are more\less than you need, you can set the minimal flag for less features or the extended flag for more features:

import panel as pn

pn.Row(
    wv.Audio(
        "https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav",
        minimal=True,
        title="minimal",
    ),
    wv.Audio(
        "https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav",
        extended=True,
        title="extended",
    ),
)

<class 'bokeh.models.plots.GridPlot'>

<class 'bokeh.models.plots.GridPlot'>

This time we displayed two players side by side, to do so we used the panel library, which WaloViz is based on.
For more information, read the panel docs.

You can call the Audio function with any audio file URL or path:

# URL
wv.Audio('https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav')
# Local path
wv.Audio('local_data/CantinaBand3.wav')
# File-like-obj
with open('local_data/CantinaBand3.wav') as f:
    wv.Audio(f)
# All of the above will produce the same player

Or, if you’re processing your audio as an array or tensor, just specify the sample-rate and it’ll work:

# A tensor 
import torchaudio
wav, sr = torchaudio.load('local_data/CantinaBand3.wav')
wv.Audio((wav, sr))
wv.Audio(wav, sr=sr)
# Or a numpy array
np_wav = wav.numpy()
wv.Audio((np_wav, sr))
# All of the above will produce the same player

The save function#

When you want to capture a WaloViz player in an HTML file, just replace the Audio function with the save function:

# Local path
wv.save('local_data/CantinaBand3.wav', extended=True)
# A tensor
wav, sr = torchaudio.load('local_data/CantinaBand3.wav')
wv.save((wav, sr))
wv.save(wav, sr=sr)
# All of the above will produce the same HTML

The default output file path is waloviz.html, you can specify your own path like so:

wv.save('local_data/CantinaBand3.wav', 'your/own/path.html')
wv.save('local_data/CantinaBand3.wav', out_file='your/own/path.html')
# All of the above will produce the same HTML
This web page was generated from a Jupyter notebook and not all interactivity will work on this website. Right click to download and run locally for full Python-backed interactivity.

The extension function#

It allows to prepare the visualization libraries and settings for your favorite notebook editor:
wv.extension()
Calling extension lets WaloViz know that you are about to use it in a notebook, you to do it just once.
Don’t think about it too much, that’s how many libraries operate (such as holoviews or panel), and it works!